ProcID specifies the picture button’s appearance and behavior characteristics. It is used by the button to determine its behavioral characteristics, and how it looks when selected or deselected, enabled or disabled, and when the button’s value is changed. The value for this 4-byte long integer can be specified either by adding a set of constants to obtain the desired result, or using a specially defined variant record, as illustrated below:
picbutInstantEvent Report a picture button event as soon as the
mouse-down occurs in the button. This option
is best utilized with “click sensitive”
icons, such as the ones seen in the Chooser.
Instant events are automatically turned on
when you turn on the “repeating events”
option.
picbutTrackWithHilite Draw a tracking highlight (a bold outline
around the button, similar to the one used by
the toolbox’s radio buttons) when the mouse
button is down and its cursor is inside the
button’s area.
picbutLockSelected When the user selects the button, lock it in
the selected state thereby disallowing the
user to deselect it. This option is usually
used to produce the functionality of radio
buttons, where a button can be turned on by
clicking on it, but the user has to click
another button to turn this one off. If you
turn on this option, the “switch selected”
and “repeating events” options are
automatically turned off.
picbutSwitchSelected When the user clicks the button, reverse the
“selection” state (i.e., if currently
selected, switch to deselected. If currently
deselected, switch to selected). This option
produces a simple click-on/click-off type of
button using a single stage. If you turn on
this option, the “lock selected” and
“repeating events” options are automatically
turned off.
picbutRepeatEvents Repeated doPictButton events are produced as
long as the mouse button is down and its
cursor is inside the button’s area. These
events can optionally increment/decrement the
button’s value at a specified rate. This
option is useful for button’s that control
movement of objects, or situations where the
button’s value may change by more than one.
If you turn on this option, the “instant
events” option is automatically turned off.
picbutAutoValueChg Automatically increment/decrement the
button’s value when it is selected by the
user. If this option is not used, your
application must manually change button
values where applicable. Automatic value
changing is only useful if your button has a
range of values through which is can
progress.
picbutScaleLinear This option controls the speed of automatic
value changes when the “repeat events” option
is turned on. After an initial pause, the
button’s value will increment/decrement at a
fixed rate. This option can only be used in
conjunction with the “automatic value change”
option. You may specify only one of the four
possible rates for automatic value changes:
Linear (default), slow acceleration, medium
acceleration, or fast acceleration.
picbutScaleSlowAccel Same as above, but the rate accelerates
slowly.
picbutScaleMedAccel Same as above, but the rate accelerates at a
moderate rate.
picbutScaleFastAccel Same as above, but the rate accelerates
rapidly.
picbutValueWrap When a button’s value reaches either the high
or low limit, start at the opposite end of
the range. This option can only be used in
conjunction with the “automatic value change”
option.
picbutLeftRightSplit Clicking on the left half of the button
decrements the button’s value, while clicking
on the right half increments it. You cannot
combine this option with the top/bottom
split.
picbutTopBottomSplit Clicking on the bottom half of the button
decrements the button’s value, while clicking
on the top half increments it. If you turn
on this option, the “left/right split” option
is automatically turned off.
picbutMultiStage The button has a different image for each of
its possible values. Note that even with
this option turned off, you may still decide
to use an alternate image for a selected
button and/or a disabled button.
picbutBigSICN3D If you are using an SICN icon to produce a 3D
button, you can create a slightly larger
button (24 x 22 pixels) with more pronounced
shading. Without this option, SICN icons
produce a slightly smaller button (24 x 20
pixels).
picbutUsePICTS Use PICTs instead of icons for the button’s
image(s). Note that PICTs and icons use
different resource numbering schemes. See
the relevant details earlier in this chapter.
picbutGray4use8 If your 8-bit PICTs look good on 4-bit gray
scale monitors, turn this option on to allow
them to be used in such a way. Otherwise, a
4-bit PICT is required when a monitor is
set to 4-bits. This option can only be used
in conjunction with the “use PICTs” option.
Selection Effects (Choose only one)…
picbutSelectDarken Darken the button’s image when it is
selected.
picbutSelectDarkenSICN3D Darken and “push in” a 3D button when it is
selected. An SICN resource is used for the
button’s image. Tools Plus converts the SICN
to a 3D color button, and formulates all the
necessary selected and disabled images.
picbutSelectLightenSICN3D Lighten and “push in” a 3D button when it is
selected. An SICN resource is used for the
button’s image. Tools Plus converts the SICN
to a 3D color button, and formulates all the
necessary selected and disabled images.
picbutSelectPushedSICN3D “Push in” a 3D button when it is selected,
but don’t darken or lighten the button. An
SICN resource is used for the button’s image.
Tools Plus converts the SICN to a 3D color
button, and formulates all the necessary
selected and disabled images. This option is
suitable for momentary push buttons (like the
Macintosh’s standard push button), because
they provide little visual feedback that the
button is selected.
picbutSelectAltImage Use an alternate image when the button is
selected. If the button is multistage, a
selected image will likely be required for
each stage.
Disabling Effects (Choose only one)…
If a disabling effect is not specified, the global default is used as defined by the DefaultIconLook routine.
picbutDimUsingBlackLite When the button is disabled, overlay the
image with a black color using a “light gray”
(25%) pattern.
picbutDimUsingWhiteLite When the button is disabled, overlay the
image with a white color using a “light gray”
(25%) pattern.
picbutDimUsingWhite When the button is disabled, overlay the
image with a white color using a “medium
gray” (50%) pattern.
picbutDimLeaveBorder When the button is disabled, do not apply the
disabling effect to the image’s border. This
option can be used in conjunction with any of
the disabling effects listed above.
picbutDimAltImage Use an alternate image when the button is
disabled. If the button is multistage, a
selected image will likely be required for
each stage. You may have to create a
disabled image for both the selected and
deselected state if the button can be seen in
such a way.
picbutDimNoChange The button appears unchanged when it is
disabled. The user is beeped if they click
on a disabled button.
So, if you want to create a large SICN 3D picture button that locks into the selected state, lightens when selected, and is disabled by overlaying the image using a white color with a 50% gray pattern, you should use the combined constants picbutLockSelected + picbutBigSICN3D + picbutSelectLightenSICN3D + picbutDimUsingWhite. Alternatively, a C structure and a Pascal variant record are available to help you define the ProcID in a more intuitive way, as shown below:
union TPPictButtonSpec { /*Picture Button's appearance and */
/* behavior specs in 2 formats… */
struct{ /* • Parsed into components: */
unsigned short InstantEvent: 1; /* Report event on mouse-down */
unsigned short TrackWithHilite: 1; /* Track using hilighting */
/* (like a radio button) */
unsigned short LockSelected: 1; /* Lock if selected (mouse */
/* can't deselect) */
unsigned short SwitchSelected: 1; /* Switch 'select' state if */
/* clicked. */
unsigned short RepeatEvents: 1; /* Repeat event when button is*/
/* held. */
unsigned short AutoValueChg: 1; /* Automatically chg button's */
/* value. */
unsigned short AutoValueScaling: 3;/* Rate of change for button's*/
/* value. */
unsigned short ValueWrap: 1; /* Button's range of values */
/* 'wrap' around. */
unsigned short LeftRightSplit: 1; /* Left side reduces value, */
/* right increase. */
unsigned short TopBottomSplit: 1; /* Top increases value, bottom*/
/* reduces. */
unsigned short MultiStage: 1; /* Button has multiple stages */
unsigned short BigSICN3D: 1; /* Make SICN 3D button larger */
unsigned short UsePICTS: 1; /* Use PICTs instead of icons */
unsigned short Gray4use8: 1; /* Use 8-bit color pict on */
/* 4-bit gray scale monitor.*/
/*Selection Effects… */
unsigned short SelectDarken: 1; /* Darken image */
unsigned short SelectDarkenSICN3D: 1; /* Darken (+push in) a 3D */
/* SICN icon. */
unsigned short SelectLightenSICN3D: 1;/* Lighten (+push in) 3D */
/* SICN icon. */
unsigned short SelectPushedSICN3D: 1; /* Same color (+push) 3D */
/* SICN icon. */
unsigned short bit19: 1; /* (reserved bit) */
unsigned short bit20: 1; /* (reserved bit) */
unsigned short SelectAltImage: 1; /* Use an alternate image */
unsigned short bit22: 1; /* (reserved bit) */
/*Disabling Effects… */
unsigned short DimUsingBlackLite: 1;/* Overlay Black color, Lt */
/* Gray pattern. */
unsigned short DimUsingWhiteLite: 1;/* Overlay White color, Lt */
/* Gray pattern. */
unsigned short DimUsingWhite: 1; /* Overlay White color, Gray */
/* pattern. */
unsigned short bit26: 1; /* (reserved bit) */
unsigned short bit27: 1; /* (reserved bit) */
unsigned short DimLeaveBorder: 1; /* Leave border when effect */
/* applied. */
unsigned short DimAltImage: 1; /* Use an alternate image */
unsigned short DimNoChange: 1; /* Button looks same when */
/* disabled. */
unsigned short bit31: 1; /* (reserved bit) */
} Bits; /* */
long Num; /* • Long equivalent */
}; /* */
typedef union TPPictButtonSpec TPPictButtonSpec;
TPPictButtonSpec = packed record {Picture Button's appearance &behavior}
{ specifications in 2 formats… }
case integer of { }
0: ( { • Parsed into components: }
InstantEvent: boolean; { Report event on mouse-down }
TrackWithHilite: boolean; { Track using hilighting, like}
{ a radio button. }
LockSelected: boolean; { Lock if selected (mouse }
{ can't deselect) }
SwitchSelected: boolean; { Switch 'selected' state if }
{ clicked }
RepeatEvents: boolean; { Repeat event when button is }
{ held down }
AutoValueChg: boolean; { Automatically change }
{ button's value }
AutoValueScaling: 0..3; { Rate of change for button's }
{ value. }
ValueWrap: boolean; { Button's range of values }
{ 'wrap' around }
LeftRightSplit: boolean; { Left side reduces value, }
{ right increases. }
TopBottomSplit: boolean; { Top increases value, bottom }
{ reduces. }
MultiStage: boolean; { Button has multiple stages }
BigSICN3D: boolean; { Create a larger SICN 3D }
{ button }
UsePICTS: boolean; { Use PICTs instead of icons }
Gray4use8: boolean; { Use 8-bit color pict on }
{ 4-bit gray monitor }
{Selection Effects… }
SelectDarken: boolean; { Darken image }
SelectDarkenSICN3D: boolean; { Darken (and push in) a 3D }
{ SICN icon. }
SelectLightenSICN3D: boolean; { Lighten (and push in) a 3D }
{ SICN icon. }
SelectPushedSICN3D: boolean; { Same color (and push in) a }
{ 3D SICN icon. }
bit19, bit20: boolean; { (reserved bits) }
SelectAltImage: boolean; { Use an alternate image }
bit22: boolean; { (reserved bit) }
{Disabling Effects… }
DimUsingBlackLite: boolean; { Overlay Black color using Lt}
{ Gray pattern }
DimUsingWhiteLite: boolean; { Overlay White color using Lt}
{ Gray pattern }
DimUsingWhite: boolean; { Overlay White color using }
{ Gray pattern }
bit26, bit27: boolean; { (reserved bits) }
DimLeaveBorder: boolean; { Leave border when applying }
{ effect. }
DimAltImage: boolean; { Use an alternate image }
DimNoChange: boolean; { Button looks the same when }
{ disabled. }
bit31: boolean; { (reserved bit) }
); { }
1: ( {• Longint equivalent: }
Num: longint; { Specification longint }
); { }
end;
As an example, lets create a picture button that repeats events, uses an alternate image when selected, and looks the same when disabled. The following code sample illustrates how this is done:
procedure DoItNow;
var
ProcID: TPPictButtonSpec; {Define the variable used for the ProcID}
begin
ProcID.Num := 0; {Initialize all the bits to zero values }
ProcID.RepeatEvents := true; {Button will produce repeating events}
ProcID.SelectAltImage := true;{Alternate image is used when button}
{ is selected. }
ProcID.DimNoChange:= true; {Button looks the same when disabled}
You can use whatever you like best as the ProcID, a single constant, several constants added together, a variable, or the long integer component of a structure or variant record.
Rate of Repeating Events
````````````````````````
Picture buttons have the ability to produce repeating events when they are held down. Four predefined rates are available to control the speed at which a picture button’s value changes:
• Linear: The button’s value changes when the button is
selected. After a brief pause, the value
continues to change at a slow and consistent
rate.
• Slow Acceleration: The button’s value changes when the button is
selected. After a brief pause, the value
continues to change at a rate that slowly
accelerates.
• Medium Acceleration: The button’s value changes when the button is
selected. After a brief pause, the value
continues to change at a moderately accelerating
rate.
• Fast Acceleration: The button’s value changes when the button is
selected. After a brief pause, the value
continues to change at a rate that rapidly
accelerates.
There is yet another way to control a button’s speed, and that is by using the SetPictButtonSpeed procedure which lets you specify an exact rate (change in value per second). When you use SetPictButtonSpeed, the specified rate takes effect immediately when the user presses the picture button. Unlike the four standard Tools Plus acceleration rates, there is no pause between the time when the user selects the picture button and when the repeating events begin.
Note: If your application calls PollSystem more often than the picture
button’s rate of change, your application will receive doNothing
events (no event). This produces no ill effects, but you should
be aware that it is possible to receive doNothing events between
doPictButton events.
CONST {Pict Button Behavior and Appearance Specs: }
picbutInstantEvent = $80000000; { Report event on mouse-down }
picbutTrackWithHilite= $40000000; { Track using hiliting, like a }
{ radio button. }
picbutLockSelected = $20000000; { Lock if selected (mouse can't }
{ deselect) }
picbutSwitchSelected = $10000000; { Switch 'selected' state if }
{ clicked. }
picbutRepeatEvents = $08000000; { Repeat event when button is }
